README: Visual Style Classification and VSD Analysis
===================================================

This package provides a script for classifying images into five style categories
using a DINOv2 backbone and a trained linear head. It also computes the Visual
Style Dominance (VSD) score with bootstrap confidence intervals.

----------------------------------------------------------------------
Requirements
----------------------------------------------------------------------

- Python 3.9 or higher
- PyTorch >= 2.0
- torchvision
- Pillow

Install with pip if needed:

    pip install torch torchvision pillow

----------------------------------------------------------------------
Files
----------------------------------------------------------------------

- vsd_inference.py        Main script
- linear_head_final.pt    Trained linear head weights
- README.txt              This file

----------------------------------------------------------------------
Input Format (CSV)
----------------------------------------------------------------------

You must provide a CSV file with the following columns:

- image_path   Path to the image (absolute or relative to --images-root)
- model        Name of the generative model (used for grouping)
- period       Name of the historical period (used for grouping)

Example (metadata.csv):

    image_path,model,period
    images/Flux_Schnell/Centuries/21st_century/sample1.png,Flux_Schnell,21st_century
    images/SDXL/Centuries/19th_century/sample2.png,SDXL,19th_century

----------------------------------------------------------------------
Usage
----------------------------------------------------------------------

Run the script as follows:

    python vsd_inference.py \
      --images-root /path/to/images \
      --head-path linear_head_final.pt \
      --backbone dinov2_vitb14 \
      --labels drawing engraving illustration painting photography \
      --csv metadata.csv \
      --out-dir results

Arguments:
- --images-root   Base folder where images are located
- --head-path     Path to the trained linear head checkpoint
- --backbone      DINOv2 backbone variant 
- --labels        Style categories in the exact training order
- --csv           Path to the CSV metadata file
- --out-dir       Directory where results will be written

----------------------------------------------------------------------
Outputs
----------------------------------------------------------------------

The script produces three CSV files in the output directory:

1. per_image_predictions.csv
   One row per image with predicted label, confidence, model, and period.

2. style_distributions.csv
   For each (model, period): proportions and counts of styles.

3. vsd_summary.csv
   For each (model, period): VSD score, 95% CI (ci_low, ci_high), and n.

----------------------------------------------------------------------